.TH "frovedis::sliced_blockcyclic_matrix<T>" "" "" "" ""
.SH NAME
.PP
\f[C]frovedis::sliced_blockcyclic_matrix<T>\f[] \- a data structure
containing the slicing information of a two\-dimensional
\f[C]frovedis::blockcyclic_matrix<T>\f[]
.SH SYNOPSIS
.PP
\f[C]#include\ <frovedis/matrix/sliced_matrix.hpp>\f[]
.SS Constructors
.PP
sliced_blockcyclic_matrix ()
.PD 0
.P
.PD
sliced_blockcyclic_matrix (const \f[C]blockcyclic_matrix<T>\f[]& m)
.SS Public Member Functions
.PP
void set_num (size_t nrow, size_t ncol)
.SS Public Data Members
.PP
\f[C]node_local<sliced_blockcyclic_matrix_local<T>>\f[] data
.PD 0
.P
.PD
size_t num_row
.PD 0
.P
.PD
size_t num_col
.SH DESCRIPTION
.PP
In order to perform matrix operations on sub\-matrices instead of entire
physical matrix, frovedis provides some sliced data structures.
\f[C]sliced_blockcyclic_matrix<T>\f[] is one of them.
It is actually not a real matrix, rather it only contains some slicing
information of a physical \f[C]blockcyclic_matrix<T>\f[].
Thus any changes performed on the sliced matrix, would actually make
changes on the physical matrix from which slice was made.
.PP
Like \f[C]blockcylic_matrix<T>\f[], a
\f[C]sliced_blockcyclic_matrix<T>\f[] is also a template based structure
with type \f[B]"T"\f[] which can be either \f[B]"float"\f[] or
\f[B]"double"\f[] (at this moment).
Specifying other types can cause floating point exception issues.
.PP
A \f[C]sliced_blockcyclic_matrix<T>\f[] contains public member "data" of
the type
.PD 0
.P
.PD
\f[C]node_local<sliced_blockcyclic_matrix_local<T>>\f[].
The actual distributed sliced matrices are contained in all the worker
nodes locally, thus named as
\f[C]sliced_blockcyclic_matrix_local<T>\f[].
Each of this local matrix has the below structure:
.IP
.nf
\f[C]
template\ <class\ T>
struct\ sliced_blockcyclic_matrix_local\ {
\ \ T\ *data;\ \ //\ pointer\ to\ the\ beginning\ of\ the\ physical\ local\ matrix
\ \ int\ *descA;\ //\ pointer\ to\ the\ descriptor\ array\ of\ the\ physical\ local\ matrix
\ \ size_t\ IA;\ \ //\ row\-id\ of\ the\ physical\ matrix\ starting\ row\ from\ which\ to\ slice\ 
\ \ size_t\ JA;\ \ //\ col\-id\ of\ the\ physical\ matrix\ starting\ col\ from\ which\ to\ slice
\ \ size_t\ sliced_num_row;\ \ //\ number\ of\ rows\ in\ the\ global\ sliced\ matrix
\ \ size_t\ sliced_num_col;\ \ //\ number\ of\ columns\ in\ the\ global\ sliced\ matrix
};
\f[]
.fi
.PP
E.g., if a physical \f[C]blockcyclic_matrix<T>\f[] M has dimension 4x4
and slice is needed from 2nd row and 2nd column till 3rd row and 3rd
column, then
.PD 0
.P
.PD
"data" in each node will hold the address of local blockcyclic matrix of
that node (data \-> &local_m[0][0]),
.PD 0
.P
.PD
"descA" in each node will hold the address of the array descriptor of
the local blockcyclic matrix of that node (descA \-> &local_m.descA[0]),
.PD 0
.P
.PD
"IA" will be 2 (starting from 2nd row \- so row id is 2),
.PD 0
.P
.PD
"JA" will be 2 (starting from 2nd column \- so col id is 2),
.PD 0
.P
.PD
From 2nd row till 3rd row, number of rows to be sliced is 2, thus
"sliced_num_row" would be 2.
.PD 0
.P
.PD
From 2nd column till 3rd column, number of columns to be sliced is 2,
thus "sliced_num_col" would be 2.
.PP
Kindly note that IA and JA do not contain the index, instead they
contain the id.
And also in each local sliced matrices the sliced information IA, JA,
sliced_num_row, sliced_num_col would be same.
The only difference would be in the pointer values, i.e., in data and
descA.
.PP
The global version, \f[C]sliced_blockcyclic_matrix<T>\f[] at master node
actually contains nothing but the reference to these local sliced
matrices at worker nodes and the global matrix dimension, i.e., the
actual number of rows and columns in the physical global blockcyclic
matrix.
It has the below structure:
.IP
.nf
\f[C]
template\ <class\ T>
struct\ sliced_blockcyclic_matrix\ {
\ \ node_local<sliced_blockcyclic_matrix_local<T>>\ data;\ //\ local\ matrix\ information
\ \ size_t\ num_row;\ \ \ //\ actual\ number\ of\ rows\ in\ physical\ global\ matrix
\ \ size_t\ num_col;\ \ \ //\ actual\ number\ of\ columns\ in\ physical\ global\ matrix
};
\f[]
.fi
.PP
Such matrices are very useful in operations of external libraries like
pblas, scalapack etc.
.SS Constructor Documentation
.SS sliced_blockcyclic_matrix ()
.PP
Default constructor.
It creates an empty sliced matrix with num_row = num_col = 0 and local
data pointers pointing to NULL.
Basically of no use, unless it is needed to manipulate the slice
information manually.
.SS sliced_blockcyclic_matrix (const \f[C]blockcyclic_matrix<T>\f[]& m)
.PP
Special constructor for implicit conversion.
This constructor treats an entire physical matrix as a sliced matrix.
Thus the created \f[C]sliced_blockcyclic_matrix<T>\f[] would have same
dimension as with the input \f[C]blockcyclic_matrix<T>\f[] and local
data pointers pointing to the base address of the local blockcyclic
matrices.
.SS Public Member Function Documentation
.SS void set_num (size_t nrow, size_t ncol)
.PP
This function sets the "num_row" and "num_col" fields with the actual
number of rows and columns in the global physical blockcyclic matrix.
Only useful when manual manipulation is required.
.SS Public Data Member Documentation
.SS data
.PP
An instance of \f[C]node_local<sliced_blockcyclic_matrix_local<T>>\f[]
which contains the references to the local sliced matrices in the worker
nodes.
.SS num_row
.PP
A size_t attribute to contain the actual number of rows in the physical
global blockcyclic matrix.
.SS num_col
.PP
A size_t attribute to contain the actual number of columns in the
physical global blockcyclic matrix.
.SS Public Global Function Documentation
.SS make_sliced_blockcyclic_matrix ()
.PP
This utility function accepts a valid
\f[C]sliced_blockcyclic_matrix<T>\f[] and slicing information like row
and column index from which slicing is to be started, and the size of
the output sliced matrix, i.e., number of rows and columns to be sliced
from the starting location.
On receiving the valid inputs, it outputs a
\f[C]sliced_blockcyclic_matrix<T>\f[] object containing the reference to
the local sliced matrices, else it throws an exception.
It has the below syntax:
.IP
.nf
\f[C]
sliced_blockcyclic_matrix<T>\ 
make_sliced_blockcyclic_matrix\ (const\ sliced_blockcyclic_matrix<T>&\ mat,
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ size_t\ start_row_index,
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ size_t\ start_col_index,
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ size_t\ num_row,
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ size_t\ num_col);
\f[]
.fi
.PP
Please note that in case a \f[C]blockcyclic_matrix<T>\f[] is passed to
this function, the entire matrix would be treated as a
\f[C]sliced_blockcyclic_matrix<T>\f[] because of the implicit conversion
constructor (explained above).
Thus this function can be used to obtain a sliced matrix from both a
physical \f[C]blockcyclic_matrix<T>\f[] and a valid
\f[C]sliced_blockcyclic_matrix<T>\f[].
.PP
\f[B]Example\f[]: If a physical \f[C]blockcyclic_matrix<T>\f[] "mat" has
the dimension 4x4 and slicing is required from its 2nd row and 2nd
column till 4th row and 4th column, then this function should be called
like:
.IP
.nf
\f[C]
auto\ smat\ =\ make_sliced_blockcyclic_matrix(mat,1,1,3,3);
\f[]
.fi
.PP
Index of the 2nd row is 1, thus start_row_index = 1
.PD 0
.P
.PD
Index of the 2nd column is 1, thus start_col_index = 1
.PD 0
.P
.PD
From 2nd row till 4th row, number of rows to be sliced is 3, thus
num_row = 3
.PD 0
.P
.PD
From 2nd column till 4th column, number of columns to be sliced is 3,
thus num_col = 3
.IP
.nf
\f[C]
Input\ (mat):\ \ \ \ \ \ \ \ Output\ (smat):
\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-
1\ 2\ 3\ 4\ \ \ \ \ \ \ \ \ \ \ \ \ 6\ 7\ 8
5\ 6\ 7\ 8\ \ \ \ \ \ \ =>\ \ \ \ 7\ 6\ 5
8\ 7\ 6\ 5\ \ \ \ \ \ \ \ \ \ \ \ \ 3\ 2\ 1
4\ 3\ 2\ 1
\f[]
.fi
.PP
Now if we need to slice further this sliced matrix, "smat" from its 2nd
row and 2nd column till 3rd row and 3rd column, then we would call this
function like below:
.IP
.nf
\f[C]
auso\ ssmat\ =\ make_sliced_blockcyclic_matrix(smat,1,1,2,2);
\f[]
.fi
.PP
Index of the 2nd row of smat is 1, thus start_row_index = 1
.PD 0
.P
.PD
Index of the 2nd column of smat is 1, thus start_col_index = 1
.PD 0
.P
.PD
From 2nd row till 3rd row of smat, number of rows to be sliced is 2,
thus num_row = 2
.PD 0
.P
.PD
From 2nd column till 3rd column of smat, number of columns to be sliced
is 2, thus num_col = 2
.PP
Kindly note that 2nd row of "smat" is actually the 3rd row of the
physical matrix "mat", but this function takes care of it internally.
Thus you just need to take care of the index of the input sliced matrix,
not the actual physical matrix
.IP
.nf
\f[C]
Input\ (smat):\ \ \ \ \ \ \ Output\ (ssmat):
\-\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
6\ 7\ 8\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 6\ 5
7\ 6\ 5\ \ \ \ \ \ \ \ \ =>\ \ \ \ 2\ 1
3\ 2\ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 
\f[]
.fi
.PP
The above input/output is presented just to explain the slicing concept.
The internal storage representation of these sliced blockcyclic matrices
would be a bit different and complex in nature.
.SH SEE ALSO
.PP
blockcyclic_matrix, sliced_blockcyclic_vector
